Skip to content

Framework contracts use direct en-US prose - #580

Open
Marius Storhaug (MariusStorhaug) wants to merge 4 commits into
mainfrom
framework-contract-prose
Open

Marius Storhaug (MariusStorhaug) wants to merge 4 commits into
mainfrom
framework-contract-prose

Conversation

@MariusStorhaug

@MariusStorhaug Marius Storhaug (MariusStorhaug) commented Nov 4, 2026 •

Copy link
Copy Markdown
Member

Framework maintainers get shorter, direct en-US specification and reference prose. The existing requirements, workflow interfaces, examples, release policy, and publication guarantees stay unchanged. Module authors do not need to change code, settings, or caller workflows.

Changed: Framework guidance states existing contracts directly

The design uses behavior and removes the subjective phrase sensible defaults. The principles describe linear version history and colocation without first-person narration. Reference descriptions use clear subjects and present tense. The patch-version description states intended compatibility instead of the absolute no risk promise, under the explicit handback in #562. This is a wording change, not a SemVer policy change or evidence of new runtime enforcement. Procedures stay imperative.

All eleven assigned pages were read in full before editing. Nine pages change; the normative specification and scenario matrix are intentional no-change reviews. No proposal-only artifact-root section is imported. The protected fingerprint mechanism and its related automation claims remain unchanged for #577. The mock-policy and major-policy decisions remain separate.

Technical details

Source and delivery identities

  • Fresh-main PR base: PSModule/Process-PSModule@64ffb1d87f86bd5d487891fdb140b78385a00531.
  • Pushed candidate: PSModule/Process-PSModule@b8a2e4ff2056409f89289a3209f5b08c3ad42031, branch framework-contract-prose, base branch main.
  • Complete scoped comparison: nine Markdown files, 47 insertions and 51 deletions. No other repository path changes.
  • The draft opened after the first real slice, 9ba4a606ca4a6aa2e460b8e994c9fdc9eff82631. Small follow-ups are 769fad09b875efec70c2fc6199f9a9c53297990f, 30d6bc69fcf8ff9c0673e8c055a3b35927f69276, and b8a2e4ff2056409f89289a3209f5b08c3ad42031. No old proposal or first-pass PR is amended.
  • Current source and issue-body ownership were rechecked before each commit. Main remained at the released source. The separate 🩹 [Patch]: Consumer artifacts stay under .PSModule #541 head remains 2001551566898e59efc764e68450c2238667d607 on complete-artifact-path-isolation; its proposal and owner branch are untouched. The recorded issue handback is the authority for existing pipeline prose, not permission to import that proposal's additions.

Writing sources

The fixed baseline is MSXOrg/docs@1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs: Documentation Model, Natural Language, Writing Guide, Markdown, Documentation, and the applicable specification/design/reference/standard templates. Their artifact distinctions remain intact; no template scaffolding is added.

The official STE overview, FAQ, and relevant Issue 9 rules were read. Issue 9 rules 3.2, 3.6, 4.1-4.2, and 6.1-6.6 informed tense, active voice, short complete sentences, and descriptive paragraphs. The locally retained official PDF MD5 is 9c720341c350ed77943b2c73d01c716f, matching the official record. No manual content is republished. The bounded review and scans do not certify full ASD-STE100 conformance.

Complete reviewed scope and before/after evidence

All paths below are under docs/content/. The before text comes from the immutable PR base above; the after text is in the pushed candidate. Natural Language supplies en-US and direct language, the Documentation Model preserves normative contracts without implying implementation, and STE guidance supplies short complete sentences and active descriptive language.

Page Review Concrete before to after Preserved distinction
specification/index.md Changed aimed at people maintaining Process-PSModule itself to for maintainers of Process-PSModule Maintainer/module-author roles, normally, and both reader links remain.
specification/spec.md No change, whole page exact FR1 still says The pipeline MUST compile the PowerShell module source code into a module artifact Every requirement, modality, FR/NFR ID, scenario, and publication/quality guarantee stays exact. A requirement is not CI evidence.
specification/design.md Changed behaviour to behavior; everything else uses sensible defaults to Other settings use defaults Same reusable entry point, caller/settings contract, phase roles, runtime enrichment, release decisions, and alternatives.
specification/principles-and-practices.md Changed we only maintain a single linear ancestry of versions to maintains one linear version history Latest-only maintenance; the 2.1.3 security fix does not go to 1.x. Dependency declarations and parameter descriptions retain their colocation examples and exact code tokens.
reference/pipeline-stages.md Changed report that is used by ... evaluate the results to report that ... uses to evaluate the test results Same report consumer, stage names/order, coverage, root-only phases, runtime paths, publication/cleanup guarantees, and artifact behavior.
reference/powershell-module-standard.md Changed resource or behaviour groups to resource or behavior groups; knobs to inputs Layout rules, normative force, test IDs, discovery precedence, examples, mock requirements, version resolution, and publication sequence remain.
reference/repository-standard.md Changed operates at the same altitude as to complements; then points to then point Unchanged MSX rules still apply. Module and non-module scope, both baseline expectations, required files, ownership, examples, and attribution requirements remain.
reference/scenario-matrix.md No change, whole page exact The scenario table, conditional cells, and all four footnotes stay exact Important-change gates, SHA matching, manual Patch releases, cleanup-only closed PRs, and stable cleanup retries remain.
reference/settings.md Changed By default, it will look for to The default path is Same JSON/YAML/PSD1 formats, .github/PSModule.yml default, authorable/runtime boundary, and complete settings/default tables and example.
reference/versioning.md Changed with protected regions with no risk of breaking functionality to intended to preserve compatibility Same major/minor/patch/no-bump classifications, optional/required parameter distinctions, examples, quoted sources, latest-only policy, and protected automation text.
reference/workflow-inputs.md Changed For how to wire it up to For caller configuration Exact inputs/defaults, four declared secrets, required flags, GitHub-token/App permission distinction, and permission example remain.

The two no-change Git blob identities are exact on base and head: specification/spec.md is 5755abf2797a699e0ef0846ac2521cb1fb90b2bb; reference/scenario-matrix.md is d9c5490f5379fe94adf94df6ac349dfc0b82b8d1.

Preservation results

Pre-edit session evidence records concrete original text, its expected wording property, and source-backed acceptance before repository edits. Nine intended wording cases fail on the original source; all eleven page-level cases pass on the pushed candidate, including the two no-change cases. The session-only comparison reports zero preservation failures.

Checked surface Result
Source structure All 120 headings, 11 explicit anchors, eight front-matter titles, and 11 requirement IDs preserved exactly and in order.
Normative/interface tokens All 144 requirement-modal tokens, 652 inline-code spans, 269 numeric literals, 233 table rows, and 148 bold labels preserved exactly and in order.
Code and examples All 22 fenced examples and every inline code example preserved exactly. Another 43 example-bearing paragraphs remain text-exact. The three narrative examples in principles use shorter prose with the same scenarios and exact literals. No example is removed.
Source links and quotations All 134 source link targets and seven quoted spans preserved exactly. No external quotation, legal text, or actual attribution is rewritten.
Rendered site All 317 rendered anchor IDs and 1,055 rendered link targets across the eleven built pages match the pre-edit site baseline. This is preservation evidence, not an external-reachability audit.
Protected passages All 13 selected policy/automation/contract passages remain text-exact after line-ending normalization.
Supported behavior Hunk review preserves supported roles, compatibility classifications, inputs/defaults, publication/recovery guarantees, dependency order, runner-only exceptions, and literal identifiers. No wording claims new shipping or CI enforcement.

The protected passages include the public-API major policy, latest-version support policy, API-fingerprint section, both related automation-claim paragraphs, mocked-environment requirement, module-owned boundary-mock rule, linear maintenance policy, version resolution/publication sequence, pipeline runtime contract, root-only phase/discovery rules, framework-generated coverage guarantee, and stable publication/cleanup section. The fingerprint source is blob ee2eafdd83405ab42da7a25aa5f6e9ff367e6d5e, base lines 127-155; its section SHA-256 remains fb098e0eea00a129b7f87f13806acc104de6ad47439769355d2d2c8fcf824e23.

The selected main pipeline page contains neither a Consumer artifact root section nor a <WorkingDirectory>/.PSModule/ token. Both remain absent. Existing paths are unchanged; no unmatched proposal content or runner-only exception is added, removed, or reinterpreted.

Existing checks and accepted review

The existing repository Markdown configuration passes on all eleven explicit paths, before edits and on the completed source:

npx --no-install markdownlint-cli2 --config .github\linters\.markdown-lint.yml docs\content\specification\index.md docs\content\specification\spec.md docs\content\specification\design.md docs\content\specification\principles-and-practices.md docs\content\reference\pipeline-stages.md docs\content\reference\powershell-module-standard.md docs\content\reference\repository-standard.md docs\content\reference\scenario-matrix.md docs\content\reference\settings.md docs\content\reference\versioning.md docs\content\reference\workflow-inputs.md

Result: 11 files, 0 issues. An initial Windows wildcard invocation selected only seven files; it was corrected to the explicit eleven-file command above, not treated as full-scope evidence.

The existing site command, zensical build --clean from docs, passes before and after the changes with No issues found. git diff --check passes for the complete base-to-head change. The session-only preservation/wording command also passes at exact pushed head b8a2e4ff2056409f89289a3209f5b08c3ad42031.

No standalone documentation-link checker is present in this main tree. The link-check scripts named in the MSX Markdown standard belong to the MSX docs repository, not this repository. No dependency was installed; no enforcement tool, prose/inventory/implementation-shape snapshot test, or repository audit document is added.

All six applicable hosted checks succeed at the exact candidate: Docs Build and Lint, repository Lint code base, CodeQL, Actions analysis, and Copilot review. Publication is skipped as expected on the draft. Copilot review was explicitly requested with the CLI-supported @copilot value. Its completed review is APPROVED at b8a2e4ff2056409f89289a3209f5b08c3ad42031, with no inline comments or active issues. Docs run, repository lint run, and hosted review run retain the results.

The coordinating parent also accepted the content at this exact head after independently reading all nine changed-page diffs and comparing all eleven pages. Its comparison preserves headings, inline literals, destinations, fences, table rows, modality sequences, the fingerprint section and related automation text, and mocked-environment requirements. This records content acceptance only; the PR remains draft and no readiness or merge action is authorized.

Alignment and residual decisions

Changed surface Standards checked Framework docs checked Result
Specification index, design, and principles Fixed MSX writing/Markdown and specification/design templates; STE clarity principles Entire released spec/design/principles set Aligned within released linguistic scope; normative spec unchanged.
Pipeline, settings, and workflow-input references Fixed MSX writing/Markdown and reference template Existing stage/runtime/caller contracts and scenario matrix Aligned; all contract tables/examples and protected guarantees unchanged.
Module and repository standards Fixed MSX writing/Markdown and standard template Layout, repository roles, test, version, and publishing guidance Aligned; mock-policy conflict remains #563.
Versioning reference Fixed MSX writing/Markdown and reference/standard templates SemVer classifications and released no-risk wording exception Aligned within handback; fingerprint truth and core/major-policy conflicts remain #577 and #573.

The delivery issue's pre-edit read, expectations, baseline, small-commit wording, ownership-recheck, and local current-head validation steps are complete. The scoped convergence sweep covered open documentation-writing-alignment issues, the protected follow-ups, the eleven owned paths, and the disjoint first-pass PR paths. No additional issue is closed by this bounded prose change.

Residual decisions are precise: #577 reconciles the unsupported fingerprint mechanism and related claims with the real resolver after #359/#524 producer decisions; #563 decides mock policy by test category; #573 decides bootstrap-core versus complete-public-API major policy. No runtime, framework upgrade, site redesign, release-label, readiness, merge, or automation change is made. This PR stays draft.

Related references

@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

Super-linter summary

Language Validation result
CHECKOV Pass ✅
CSS Pass ✅
CSS_PRETTIER Pass ✅
GITHUB_ACTIONS Pass ✅
GITHUB_ACTIONS_ZIZMOR Pass ✅
GITLEAKS Pass ✅
GIT_MERGE_CONFLICT_MARKERS Pass ✅
HTML Pass ✅
JAVASCRIPT_ES Pass ✅
JAVASCRIPT_PRETTIER Pass ✅
MARKDOWN Pass ✅
NATURAL_LANGUAGE Pass ✅
POWERSHELL Pass ✅
PRE_COMMIT Pass ✅
SPELL_CODESPELL Pass ✅
TRIVY Pass ✅
YAML Pass ✅

All files and directories linted successfully

For more information, see the GitHub Actions workflow run

Powered by Super-linter

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approved

No active review issues block these documentation-only clarity and consistency updates.

No open issues 🎉

What changed in this PR

This documentation-only PR makes Process-PSModule’s framework specifications and references more direct and consistent with en-US prose. It preserves existing workflow contracts and release policy; module authors need no code, settings, or caller-workflow changes.

Changes:

  • Shortens descriptions of framework architecture, versioning, and colocation.
  • Clarifies reference-page wording for settings, workflow interfaces, pipeline stages, and repository standards.
  • Standardizes spelling and corrects grammar without changing executable code.
File Description
docs/​content/​specification/​principles-and-practices.md Clarifies linear versioning and colocation principles.
docs/​content/​specification/​index.md States the intended maintainer audience directly.
docs/​content/​specification/​design.md Simplifies architecture and settings-contract descriptions.
docs/​content/​reference/​workflow-inputs.md Clarifies caller-interface and credential-control wording.
docs/​content/​reference/​versioning.md Shortens version-category and compatibility explanations.
docs/​content/​reference/​settings.md States supported settings formats and the default path directly.
docs/​content/​reference/​repository-standard.md Clarifies scope and baseline requirements; corrects grammar and spelling.
docs/​content/​reference/​powershell-module-standard.md Uses en-US spelling and simplifies design-principle explanations.
docs/​content/​reference/​pipeline-stages.md Streamlines job descriptions, report wording, and failure statements.

Review effort: Balanced

@MariusStorhaug
Marius Storhaug (MariusStorhaug) marked this pull request as ready for review November 4, 2026 14:43

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[documentation-writing-alignment] State framework contracts without vague or unverified claims

2 participants